<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Low level events</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">

</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>

        <h1 class="title">Native Windows GUI: Low level events</h1>
        

        Winapi implements a bazillion of events and applications are free to define their own. There's no way for NWG to <span style="text-decoration: line-through;">catch</span>
        wrap them all. As a solution, NWG lets you use <code>bind_raw_event_handler</code> to hook the system event queue without parsing the parameters.
        <br/><br/>

        <h3>Using raw events handlers</h3>

<div class="highlight"><pre><span></span><span class="k">fn</span> <span class="nf">log_resize</span><span class="p">(</span><span class="n">window</span>: <span class="kp">&amp;</span><span class="nc">Window</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">winapi</span>::<span class="n">um</span>::<span class="n">winuser</span>::<span class="n">WM_SIZE</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">winapi</span>::<span class="n">shared</span>::<span class="n">minwindef</span>::<span class="p">{</span><span class="n">HIWORD</span><span class="p">,</span><span class="w"> </span><span class="n">LOWORD</span><span class="p">};</span><span class="w"></span>
<span class="w">    </span>
<span class="w">    </span><span class="k">const</span><span class="w"> </span><span class="n">MY_UNIQUE_RAW_HANDLER_ID</span>: <span class="kt">usize</span> <span class="o">=</span><span class="w"> </span><span class="mi">45776</span><span class="p">;</span><span class="w"></span>

<span class="w">    </span><span class="n">bind_raw_event_handler</span><span class="p">(</span><span class="o">&amp;</span><span class="n">window</span><span class="p">.</span><span class="n">handle</span><span class="p">,</span><span class="w"> </span><span class="n">MY_UNIQUE_RAW_HANDLER_ID</span><span class="p">,</span><span class="w"> </span><span class="o">|</span><span class="n">_hwnd</span><span class="p">,</span><span class="w"> </span><span class="n">msg</span><span class="p">,</span><span class="w"> </span><span class="n">_w</span><span class="p">,</span><span class="w"> </span><span class="n">l</span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="k">match</span><span class="w"> </span><span class="n">msg</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="n">WM_SIZE</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                </span><span class="n">println</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;w: {}, h: {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">LOWORD</span><span class="p">(</span><span class="n">l</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="kt">u32</span><span class="p">),</span><span class="w"> </span><span class="n">HIWORD</span><span class="p">(</span><span class="n">l</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="kt">u32</span><span class="p">));</span><span class="w"></span>
<span class="w">            </span><span class="p">},</span><span class="w"></span>
<span class="w">            </span><span class="n">_</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span>
<span class="w">        </span><span class="nb">None</span><span class="w"></span>
<span class="w">    </span><span class="p">});</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
            
        <br><br> 
        Raw event handlers work in similar way as default events handers. It works by adding a callback to a window control. This callback then gets called 
        everytime the control receives an event.
        <br/><br/>
            
        <b>The parameters:</b>
        <ul>
            <li><code>handle</code> is the handle of a window control</li>
            <li><code>id</code> is an id identifying the handler. <b>Without a different id, binding the same handler a second time on the same control will replace the first handler!</b></li>
            <li><code>f</code> is the callback that will be called. <b></b></li>
        </ul>

        <b>The return value:</b>
        <br/><br/>

        <code>RawEventHandler</code> works the same way as the normal <a href="events.html">event handler</a>.  This object is an opaque handle over the event hook
        and ignoring this value means that the callback and all its data will be leaked.
        <br/><br/>

        <b>The callback:</b>
        <br/><br/>

        The callback takes 4 arguments: <code>HWND, MSG, WPARAM, and LPARAM</code> which are the same value passed to the window procedures.
        This guide assumes you already know how to use them.
        <br/><br/>

        The callback also lets you pass a value back to the OS. If <code>None</code> is returned, the internal handler will use <code>DefSubclassProc</code> and
        execute the next event handler on the control. If a <code>Some</code> value is returned, this value will be returned by the internal handler and the following
        handlers <b>will not be called</b>.

        <br/><br/>

        Events handlers are always executed from last added to first added. Ie, user hooks will be executed before any NWG hooks.
        

        <h3>Freeing raw handlers</h3>
        
        To free a raw event handler call:
        <code>nwg::unbind_raw_event_handler(&handler)</code><br/><br/>

        <b>Calling unbind twice or trying to unbind an handler after destroying its parent will cause the function to panic.</b>
        <br/><br/>

        <h3>Checking if a raw handler is bound</h3>

        If you are not sure if a raw event handler is bound and you don't want your application to panic, use the
        <code>nwg::has_raw_handler(&handle, handler_id)</code> method.

        Example:

<div class="highlight"><pre style="width: auto; "><span></span><span class="kd">let</span><span class="w"> </span><span class="n">handler</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bind_raw_event_handler</span><span class="p">(</span><span class="o">&amp;</span><span class="n">handle</span><span class="p">,</span><span class="w"> </span><span class="mi">9001</span><span class="p">,</span><span class="w"> </span><span class="k">move</span><span class="w"> </span><span class="o">|</span><span class="n">_hwnd</span><span class="p">,</span><span class="w"> </span><span class="n">_msg</span><span class="p">,</span><span class="w"> </span><span class="n">_w</span><span class="p">,</span><span class="w"> </span><span class="n">_l</span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="nb">None</span><span class="w"></span>
<span class="p">});</span><span class="w"></span>

<span class="n">assert</span><span class="o">!</span><span class="p">(</span><span class="n">has_raw_handler</span><span class="p">(</span><span class="o">&amp;</span><span class="n">handle</span><span class="p">,</span><span class="w"> </span><span class="mi">9001</span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kc">true</span><span class="p">);</span><span class="w"></span>
</pre></div>
            
        <br/><br/>

    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
